docs: add ADR for defining API for querying permissions from MFEs for current user FC-0099 by rodmgwgu · Pull Request #60 · openedx/openedx-authz

rodmgwgu · 2025-09-19T17:39:48Z

ADR for defining an enforcement mechanism for MFEs and other clients, here we discuss about effective ways to achieve this and propose an API endpoint for permission querying.

Merge checklist:
Check off if complete or not applicable:

Version bumped
Changelog record added
Documentation updated (not only docstrings)
Fixup commits are squashed away
Unit tests added/updated
Manual testing instructions provided
Noted any: Concerns, dependencies, migration issues, deadlines, tickets

openedx-webhooks · 2025-09-19T17:39:53Z

Thanks for the pull request, @rodmgwgu!

This repository is currently maintained by @openedx/committers-openedx-authz.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

bradenmacdonald · 2025-09-19T21:05:58Z

The proposed mechanism sounds fine to me, but I wonder if we should also include a standardized way to include permissions data in "regular" backend API responses.

For example, consider an MFE that is getting a list of libraries, and the user has "edit" permission on some of the libraries but not others. The MFE would first have to GET /api/v1/libraries/ to get the list of libraries, then wait for the response, then collect the IDs of the courses and query this permissions API with a bulk query ("object": "lib:blah1", "object": "lib:other2", "object": "lib:threelib", ...) before it knows which libraries the user can edit.

Because these queries cannot happen simultaneously¹, this means that either there is a delay in showing the edit buttons (so the users see the list of libraries after it's loaded, but none of them show the "Edit" button until the permissions have also loaded, and then there is a flash of change as the edit buttons get rendered once we hear back from the authz API), or we can choose to wait until both things have loaded before showing the list of libraries, which makes the MFE feel slower.

To solve this in the Authoring MFE today (and many other parts of the platform), we use a very simple solution - include the permissions data with the "list objects" API results (example).

So, I think that this ADR should also include a standard recommendation for including a "permissions" object attached to the results of most regular GET REST API requests. i.e. Any "list objects" or "get object" API should include an extra permissions: ... field that lists all the actions the current user is allowed to take on each object.

Unless you allow an "act:edit" on "lib:*" query, which returns a list of all libraries the user can edit... ↩

rodmgwgu · 2025-09-19T22:56:45Z

The proposed mechanism sounds fine to me, but I wonder if we should also include a standardized way to include permissions data in "regular" backend API responses.

For example, consider an MFE that is getting a list of libraries, and the user has "edit" permission on some of the libraries but not others. The MFE would first have to GET /api/v1/libraries/ to get the list of libraries, then wait for the response, then collect the IDs of the courses and query this permissions API with a bulk query ("object": "lib:blah1", "object": "lib:other2", "object": "lib:threelib", ...) before it knows which libraries the user can edit.

Because these queries cannot happen simultaneously1, this means that either there is a delay in showing the edit buttons (so the users see the list of libraries after it's loaded, but none of them show the "Edit" button until the permissions have also loaded, and then there is a flash of change as the edit buttons get rendered once we hear back from the authz API), or we can choose to wait until both things have loaded before showing the list of libraries, which makes the MFE feel slower.

To solve this in the Authoring MFE today (and many other parts of the platform), we use a very simple solution - include the permissions data with the "list objects" API results (example).

So, I think that this ADR should also include a standard recommendation for including a "permissions" object attached to the results of most regular GET REST API requests. i.e. Any "list objects" or "get object" API should include an extra permissions: ... field that lists all the actions the current user is allowed to take on each object.

Footnotes

Unless you allow an "act:edit" on "lib:*" query, which returns a list of all libraries the user can edit... ↩

Thanks for this insight, definitely having the permissions information in regular API responses would simplify things going forward.

In the case of libraries, we can keep the existing information in the list objects endpoint and adapt the underlying logic to use the new authz library for evaluation.

I'm not sure how we can generalize this so we have a single standard way of including these permissions information for any kind of resource.

Perhaps, going forward we could standardize this by including in the object a property like:

"authz_permissions": {
  [key: string]: boolean
}

Where key is the "action", and the boolean indicates if it's allowed or not.

What do you think?

bradenmacdonald · 2025-09-20T00:00:06Z

I like the idea of something like that, yeah. Interested to hear what other people think.

dcoa · 2025-09-22T03:13:08Z

+   required format.
+-  401: Unauthorized, happens when the user is not authenticated/logged in.
+
+**Please note:** There is no “404 not found” case here, if the action,


I just have a question here, I'm not an expert but in my understanding Casbin will evaluate the query as denied and return false, in this kind of scenarios, if so will be difficult to the frontend give an appropriate feedback to the user whether does not have permission or the resource does not exist. Do we have this contemplated?

As much as I understand, based on a small searching and that is explained here https://ridouku.medium.com/casbin-an-alternative-to-validate-user-permissions-fd21fadc2b3a it is needed to wrap the enforcer in a function to make that validations and return the custom error.

Yes, that's my understanding, Casbin will just validate it as not allowed as it doesn't have knowledge of the actual resources on the database.

If we wanted to validate if, for example, a library exists, we would have to identify that the object we are targeting is a library (by parsing the lib: prefix), and then query the DB. This would add extra DB queries and logic which would impact on performance and complexity for maintainability.

I'm not sure if we really need to differentiate between a permission query on a non-existing resource vs just a false response. Do you see a use case where this would be important? The main use cases I have thought of are related to things like disabling edit buttons and hiding "view details" links.

I'm with @rodmgwgu on this, I think this module should be focused on whether or not the permission check passes. I can't think of a case where the front end would be querying for permissions of something that doesn't exist aside from the case of a race condition deleting a resource. Even in that case I don't think it should be authz's responsibility to communicate that information.

bmtcril

This looks good to me, thanks for writing it up!

mariajgrimaldi · 2025-09-30T09:31:54Z

+   [
+       {
+           "action": "act:read",
+           "object": "lib:test-lib",
+           "scope": "org:OpenedX"
+       },
+       {
+           "action": "act:edit",
+           "object": "lib:test-lib",
+           "scope": "org:OpenedX"
+       }
+   ]


Does this mean that if a user has permission on a scope, they automatically have permission on the object within it? If so, our decision is that scope inheritance will not be managed implicitly - sorry it wasn't part of an ADR, now it is: #76. Instead, checks must explicitly handle containment.

For example:

can(user, act:read, lib:test-lib) OR can(user, act:read, org:OpenedX)

Here, lib:test-lib and org:OpenedX are treated as separate scopes. I’m not sure if this belongs directly in this ADR, but it’s worth noting for clarity. Still I think this ADR covers this case as well, since object is optional.

FYI @bmtcril

I agree that the distinction is important and should probably be explicitly covered here as well.

@mariajgrimaldi does this mean that there won't be any cases where we want to specify both scope and object when checking for permissions with casbin? will scope and object will be the same thing now for casbin going forward?

What I'm understanding is that we will no longer have an "object" here, it will always go into "scope", even if it's an org, lib, or something else:

[ { "action": "act:read", "scope": "lib:test-lib" }, { "action": "act:edit", "scope": "org:OpenedX" } ]

Is this correct?

I updated the doc to reflect these changes and match what is being implemented on #84

@rodmgwgu: that's the level of granularity we're going with for now. It's not set in stone, since the model could later evolve to be more granular. For now, let's note that possibility but focus on describing the current, more feasible approach.

@mariajgrimaldi is this a request for a change or can this merge?

Merged! Sorry I didn't see this earlier :)

… from MFEs and other remote clients

mariajgrimaldi

LGTM! Thanks for the patience :)

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Sep 19, 2025

openedx-webhooks added this to Contributions Sep 19, 2025

github-project-automation Bot moved this to Needs Triage in Contributions Sep 19, 2025

rodmgwgu mentioned this pull request Sep 19, 2025

RBAC M4: Building the Console #16

Closed

rodmgwgu force-pushed the rod/adr-0007 branch from 3ef15d2 to 24192a5 Compare September 19, 2025 17:52

rodmgwgu marked this pull request as ready for review September 19, 2025 18:07

mphilbrick211 added the mao-onboarding Reviewing this will help onboard devs from an Axim mission-aligned organization (MAO). label Sep 19, 2025

mphilbrick211 moved this from Needs Triage to Ready for Review in Contributions Sep 19, 2025

mphilbrick211 requested a review from a team September 19, 2025 19:59

bradenmacdonald reviewed Sep 19, 2025

View reviewed changes

Comment thread docs/decisions/0007-enforcement-mechanisms-mfe.rst Outdated

Comment thread docs/decisions/0007-enforcement-mechanisms-mfe.rst

Comment thread docs/decisions/0007-enforcement-mechanisms-mfe.rst Outdated

dcoa reviewed Sep 22, 2025

View reviewed changes

sarina added the FC Relates to an Axim Funded Contribution project label Sep 22, 2025

sarina changed the title ~~docs: add ADR for defining API for querying permissions from MFEs~~ docs: add ADR for defining API for querying permissions from MFEs FC-0099 Sep 22, 2025

rodmgwgu force-pushed the rod/adr-0007 branch from 24192a5 to bbb69ea Compare September 22, 2025 19:01

bmtcril reviewed Sep 23, 2025

View reviewed changes

Comment thread docs/decisions/0007-enforcement-mechanisms-mfe.rst

Comment thread docs/decisions/0007-enforcement-mechanisms-mfe.rst Outdated

rodmgwgu force-pushed the rod/adr-0007 branch from bbb69ea to 2f52a4d Compare September 23, 2025 16:47

rodmgwgu changed the title ~~docs: add ADR for defining API for querying permissions from MFEs FC-0099~~ docs: add ADR for defining API for querying permissions from MFEs for current user FC-0099 Sep 23, 2025

mphilbrick211 moved this from Ready for Review to In Eng Review in Contributions Sep 23, 2025

bmtcril approved these changes Sep 24, 2025

View reviewed changes

mariajgrimaldi reviewed Sep 30, 2025

View reviewed changes

This was referenced Oct 2, 2025

feat(authz): [FC-0099] update state to return the libraries roles and permissions metadata openedx/frontend-app-admin-console#5

Merged

[FC-0099] feat: add rest api for roles and permissions #84

Merged

docs: ADR for Enforcement mechanisms - current user permission checks…

1351dfa

… from MFEs and other remote clients

rodmgwgu force-pushed the rod/adr-0007 branch from 9ee56c5 to 1351dfa Compare October 7, 2025 19:28

mariajgrimaldi approved these changes Oct 8, 2025

View reviewed changes

mariajgrimaldi merged commit b7ec992 into openedx:main Oct 10, 2025
14 checks passed

github-project-automation Bot moved this from In Eng Review to Done in Contributions Oct 10, 2025

Conversation

rodmgwgu commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openedx-webhooks commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bradenmacdonald commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Footnotes

Uh oh!

rodmgwgu commented Sep 19, 2025

Footnotes

Uh oh!

bradenmacdonald commented Sep 20, 2025

Uh oh!

dcoa Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bmtcril left a comment

Choose a reason for hiding this comment

Uh oh!

mariajgrimaldi Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mariajgrimaldi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

rodmgwgu commented Sep 19, 2025 •

edited

Loading

openedx-webhooks commented Sep 19, 2025 •

edited

Loading

bradenmacdonald commented Sep 19, 2025 •

edited

Loading

dcoa Sep 22, 2025 •

edited

Loading

mariajgrimaldi Sep 30, 2025 •

edited

Loading